Standard QR - API specification of Interation Operator DKIB (1.0.2)

Download OpenAPI specification:Download

Appendix D to the Technical Regulations of the Interaction Operator

Owner: Interaction Operator of CJSC'Demir Kyrgyz International Bank' (hereinafter DKIB)

The API description of interaction between Participants and Interaction Operators DKIB and other Interaction Operator.

Purpose of this document

This document provides the audience with OpenAPI specification for describing DKIB QR code collection's REST APIs. The scope of this document is limited to QR payments in Kyrgyzstan. The target audience of this document is the Developer, Business Analyst and other related Project Team Member of DKIB's client/ team (who has the basic technical know-how of Web technology such as REST or JSON).

API Use Cases

There are two major API use cases throughout this document:

  • Payments are made between banks of the DKIB network;
  • Payments are made between the bank of the DKIB network and the bank of the other Operator's network.

General flow of the process in DKIB network

Interaction between DKIB and banks in its network

Interaction_between_DKIB_and_banks_in_its_network

  1. Merchant receives QR code from QR Acquiring and provides it to the customer.
  2. Customer or purchaser scans QR code via Payment App.
  3. Payment App backend/ Sender bank system parses the information from the code and sends a request for transaction to the Interaction operator.
  4. The Interaction Operator stores transaction data and forwards request to the relevant bank.
  5. The Receiver bank gets request, makes transaction and sends response to the Interaction Operator.
  6. Then the Beneficiary bank notifies merchant about transaction.
  7. The operator forwards received response to the Sender Bank/ Payment App.
  8. Payment App shows transaction receipt to the customer.

General flow of the process in DKIB/ other Operator network

Interaction between the bank of the DKIB network and the bank of the other Operator network

Interaction_between_the_bank_of_the_DKIB_network_and_the_bank_of_the_IPC_network

  1. Merchant receives QR code from QR Acquiring and provides it to the customer.
  2. Customer or purchaser scans QR code via Payment App.
  3. Payment App backend/ Sender bank system parses the information from the code and sends a request for transaction to the Interaction operator 1.
  4. The Interaction Operator 1 receives transaction data, determines beneficiary bank, and if it is not in its network, it sends request to the relevant Interaction Operator 2.
  5. The Interaction Operator 2 gets this request and forwards it to the Beneficiary bank.
  6. The Receiver bank gets request, makes transaction and sends response to the Interaction Operator 2.
  7. Then the Beneficiary bank notifies merchant about transaction.
  8. The Interaction Operator 2 resends response to the Interaction Operator 1.
  9. The Interaction Operator 1 redirects response to the Sender bank/ Payment App.
  10. Payment App shows transaction receipt to the customer.

Logical network infrastructure

The following is a logical flow of network communication:

Logical_network_infrastructure

The transaction process

In general, there will be 5 API requests during the transaction:

  • check the details of the recipient,
  • create,
  • execute,
  • update status
  • check status.

If the final status was not received at Execute process, the recipient Bank/PSP will have to send an update status request to the Interaction Operator, as soon as the transaction is processed, the Operator in its turn will redirect the update status request to the PSP sender, this is the end of the transaction process.

However, if the final status has not been received, the Sender PSP can send a status check request to the Operator, which in its turn makes the same request to the Beneficiary Bank/PSP.

API request-response interaction, DKIB network

When interacting between banks of the DKIB network, the interaction will be exclusively between three participants: the Sending bank (Payment Application), the Receiving bank (QR Acquiring) and the DKIB interaction operator.

API Interaction between DKIB and banks in its network

API_Interaction_between_DKIB_and_banks_in_its_network

  1. First of all, Sender should check requisites so it sends API request to check beneficiary data.
  2. DKIB as Interaction operator forwards request to the Beneficiary bank.
  3. The Beneficiary bank checks data and sends response to the IO.
  4. The Operator redirects this response to the Sender bank/ Payment App.
  5. After getting the response the Sender requests transaction creating.
  6. The Interaction operator resends this request to the Receiver.
  7. Receiver gets request, creates transaction and sends response to the DKIB about creating.
  8. The IO DKIB forwards response to the sender.
  9. The sender receives response and makes transaction execute request.
  10. The IO sends this request to the Beneficiary bank.
  11. The Beneficiary bank executes transaction and makes response.
  12. The Operator redirects the response to the Payment App.
  13. If the final status was not received at the time of the execution, then the Beneficiary bank sends updated status in the Update status request to the Interaction Operator.
  14. The Interaction Operator gets final status of transaction from the Receiver bank and sends Update status request to the Sender Bank/PSP.
  15. The Sender receives final status and closes transaction, that is the end of process.

API request-response interaction, DKIB/ other Operator network

There will be 4 roles in the interaction between the banks of the DKIB network and the other Operator, the interaction operators will be intermediaries who redirect requests and responses to each other and/or to the relevant banks.

API Interaction between the bank of the DKIB network and the bank of the other Operator network

Case 1 - Sender is in DKIB Interaction Operator network and Receiver is in the IPC Interaction Operator network.

API_Interaction_between_the_bank_of_the_DKIB_network_and_the_bank_of_the_IPC_network

Case 2 - Sender is in IPC Interaction Operator network and Receiver is in the the DKIB Interaction Operator network.

api_upd_dkib_ipc

These schemes work both ways, with the only difference in checking the status of the transaction, because the process of checking the status works differently in the systems of the two interaction operators. .

When two Banks-Members of different Interaction Operators interact, the requests and responses between the Receiving bank and the Sending bank will be the same as when two banks interact with one Operator, with the only difference being that now the requests and responses will not go through one Interaction Operator, but two.

In addition, on the side of the DKIB interaction operator there will be a request/response converter from the DKIB format to the IPC format and back.

Transaction statuses

Transaction statuses

Status Description Final
10 Created No
20 In process No
50 Success Yes
30 Error Yes
40 Canceled Yes

Transaction types

Code Type Description
10 C2C Transfer by QR code/payment link.
20 C2B Purchase via QR code/payment link.
30 C2G State payment (of an individual) by QR code/payment link.
40 B2C Money transfer/withdrawal/refund by QR code/payment link.
50 B2B Payment/transfer by QR code/payment link.
60 - Electronic message on setting the reserve to the bank.
70 B2G State payment (legal entity) by QR code/payment link.

Timeout process

Timeout type Description Time
Outgoing Execute Request This timeout occurs , If the sender does not send an 'execute' request after receiving a 'create' response 1 minute
Incoming Final Status This timeout occurs in incoming QR, if our beneficiary doesn't send 'execute response' to the transaction wihtin the specified time after getting 'execute request' 5 minutes
Http response This timeout occurs when to http request of an Operator , participant doesn't resonse on time 2 seconds

Request signing and encrypting

To form a signature for POST requests, you must form a key pair (RSA 2048) - ReqPrivateKey ReqPublicKey and give ReqPublicKey to the project working group specialists in an encrypted archive.

If the header contains the signature version, by default it comes as H-SIGNING-VERSION = 1, but if the system uses the second version (described below) the header must contain H-SIGNING-VERSION = 2.

1) H-SIGNING-VERSION = 1

To form the header you need to form JWS of the sent payload request with and RSA private key. The signature is formed using ReqPrivateKey.

To from encrypted body you need to form JWE of the sent payload request with and RSA public key. The signature is formed using operator PublicKey.

Example code for generating signature and body:

import com.nimbusds.jose.*;
import com.nimbusds.jose.crypto.RSADecrypter;
import com.nimbusds.jose.crypto.RSAEncrypter;
import com.nimbusds.jose.crypto.RSASSASigner;
import com.nimbusds.jose.crypto.RSASSAVerifier;
import com.nimbusds.jose.jwk.JWK;
import com.nimbusds.jose.jwk.RSAKey;
import com.nimbusds.jwt.EncryptedJWT;
import kg.ctechnology.api.psp.exception.AppException;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;
import javax.servlet.http.HttpServletRequest;
import java.nio.file.Files;
import java.nio.file.Paths;

.....

public String signedPayload(String dtoJson, String privatePath) {
  try{
    String privateKey = new String(Files.readAllBytes(Paths.get(privatePath)));
    RSAKey rsaJWK = (RSAKey) JWK.parseFromPEMEncodedObjects(privateKey);
    JWSSigner signer = new RSASSASigner(rsaJWK);

    JWSObject jwsObject = new JWSObject(
      new JWSHeader.Builder(JWSAlgorithm.RS256).keyID(rsaJWK.getKeyID()).build(),
      new Payload(dtoJson));

    jwsObject.sign(signer);

    return jwsObject.serialize();

  } catch (Exception e){
      throw new AppException(e.getMessage());
    }
}

public String encryptPayload(String dtoJson, String privatePath, String publicPath){
  try {
    String privateKey = new String(Files.readAllBytes(Paths.get(privatePath)));
    String publicKey = new String(Files.readAllBytes(Paths.get(publicPath)));

    RSAKey rsaJWK = (RSAKey) JWK.parseFromPEMEncodedObjects(privateKey);
    RSAKey rsaPublicJWK = (RSAKey) JWK.parseFromPEMEncodedObjects(publicKey);

    JWEEncrypter encrypter = new RSAEncrypter(rsaPublicJWK);

    JWSObject jwsObject = new JWSObject(
      new JWSHeader.Builder(JWSAlgorithm.RS256).keyID(rsaJWK.getKeyID()).build(),
      new Payload(dtoJson));

    JWSSigner signer = new RSASSASigner(rsaJWK);
    jwsObject.sign(signer);
    JWEObject jweObject = new JWEObject(
      new JWEHeader.Builder(JWEAlgorithm.RSA_OAEP_256, EncryptionMethod.A256GCM)
        .contentType("JWT")
        .build(),
      new Payload(jwsObject));

    jweObject.encrypt(encrypter);

    return jweObject.serialize();

  } catch (Exception ex){
    throw new AppException(ex.getMessage());
  }
}

2) H-SIGNING-VERSION = 2

The OPENSSL DGST SHA256 in base64 format will be used to sign requests.

import com.nimbusds.jose.*;

public String sign(String payload, String privatePath) {
  try{
    Signature signature = Signature.getInstance("SHA256withRSA");
    String privateKeyFile = new String(Files.readAllBytes(Paths.get(privatePath)));
    RSAKey rsaKey = (RSAKey) JWK.parseFromPEMEncodedObjects(privateKeyFile);
    PrivateKey privateKey = rsaKey.toPrivateKey();
    signature.initSign(privateKey);
    signature.update(payload.getBytes(StandardCharsets.UTF_8));
    byte[] signatureValue = signature.sign();
    return Base64.encodeBase64String(signatureValue);
  }catch (Exception e){
    throw new AppException(e.getMessage());
  }
}

public void verify(String payload, String sign, String publicPath) {
  try{
    Signature signature = Signature.getInstance("SHA256withRSA");
    String publicKeyFile = new String(Files.readAllBytes(Paths.get(publicPath)));
    RSAKey rsaKey = (RSAKey) JWK.parseFromPEMEncodedObjects(publicKeyFile);
    PublicKey publicKey = rsaKey.toPublicKey();
    signature.initVerify(publicKey);
    byte[] data = payload.getBytes(StandardCharsets.UTF_8);
    signature.update(data);
    if(!signature.verify(Base64.decodeBase64(sign))){
      throw new AccessDeniedException("Доступ к системе запрещен");
    }
  }catch (Exception e){
    throw new AppException(e.getMessage());
  }
}

API Requests

It should be considered that the member banks interact exclusively with the Interaction Operator, i.e. all API requests/responses are received from the Interaction Operator, which in its turn processes all requests/responses and forms new requests/responses on their basis in order to forward them to another member bank.

It should also be noted that the scanning part must transfer all the content data in the acquirer's QR code, regardless of the mandatory nature of this field in the API queries.

Sender part API's

Sender Bank/PSP sends requests to the Interaction Operator, and the Interaction Operator returns the response.

Check requisites

path Parameters
qrVersion
required
string

Version of QR, by default "1", Field ID=00 from QR

header Parameters
H-PSP-TOKEN
required
string

Token for Payment system/ Sender Bank

H-PSP-ID
required
string

Payment system/ Sender bank indentificator

H-HASH
required
string

Signature of request

Request Body schema: application/json
Array
qrType
required
string
Enum: "staticQr" "dynamicQr"

Payment link type, Field ID=01 from QR

merchantProvider
required
string <= 32

Unique identificator of merchant provider, Field ID=32, SubID=00 from QR

merchantId
string <= 32

Service provider name, Field ID=59 from QR

serviceId
string <= 32

Service code in the Payment system, Field ID=32, SubID=01 from QR

serviceName
string <= 32

Service name in the Payment system, Field ID=33 SubID=01 from QR

beneficiaryAccountNumber
string <= 32

Unique identifier of the payer within the service (лицевой счет), Field ID=32, SubID=10 from QR

merchantCode
required
integer <= 4

Service provider code (MCC), Field ID=52 from QR

currencyCode
required
string <= 3

Currency, by default always "417", Field ID=53 from QR

qrTransactionId
string <= 32

Transaction ID, Field ID=32, SubID=11 from QR

qrComment
string <= 32

Comment for payment, Field ID=34

customerType
required
string
Enum: 1 2

1 - Individual; 2 - Corp; Client type of sender, from system of Payment App/ Sender Bank

amount
required
integer <= 13

Payment amount (in tyiyns), could be from QR or from Payment App/ Sender Bank

qrLinkHash
required
string <= 4

Last 4 symbols of payment link hash string, Field ID=63 from QR

Array of objects

Additional fields for the sender, a maximum of 3 additional keys and values can be stored

Responses

Request samples

Content type
application/json
{
  • "qrType": "staticQr",
  • "merchantProvider": "qr.demirbank.kg",
  • "merchantId": "DKIB",
  • "serviceId": "7001",
  • "serviceName": "transfer",
  • "beneficiaryAccountNumber": "11800000971044802",
  • "merchantCode": 4829,
  • "currencyCode": "417",
  • "qrTransactionId": "1732832",
  • "qrComment": "comment",
  • "customerType": "1",
  • "amount": 40000,
  • "qrLinkHash": "67D9",
  • "extra": [
    ]
}

Response samples

Content type
application/json
{
  • "beneficiaryName": "c***e A***o",
  • "transactionType": "10",
  • "extra": [
    ]
}

Create transaction

path Parameters
qrVersion
required
string

Version of QR, by default "1", Field ID=00 from QR

header Parameters
H-PSP-TOKEN
required
string

Token for Payment system/ Sender Bank

H-PSP-ID
required
string

Payment system/ Sender bank indentificator

H-HASH
required
string

Signature of request

Request Body schema: application/json
Array
qrType
required
string
Enum: "staticQr" "dynamicQr"

Payment link type, Field ID=01 from QR

merchantProvider
required
string <= 32

Unique identificator of merchant provider, Field ID=32, SubID=00 from QR

merchantId
string <= 32

Service provider name, Field ID=59 from QR

serviceId
string <= 32

Service code in the Payment system, Field ID=32, SubID=01 from QR

serviceName
string <= 32

Service name in the Payment system, Field ID=33 SubID=01 from QR

beneficiaryAccountNumber
string <= 32

Unique identifier of the payer within the service (лицевой счет), Field ID=32, SubID=10 from QR

merchantCode
required
integer <= 4

Service provider code (MCC), Field ID=52 from QR

currencyCode
required
string <= 3

Currency, by default always "417", Field ID=53 from QR

qrTransactionId
string <= 32

Transaction ID, Field ID=32, SubID=11 from QR

qrComment
string <= 32

Comment for payment, Field ID=34

customerType
required
string
Enum: 1 2

1 - Individual; 2 - Corp; Client type of sender, from system of Payment App/ Sender Bank

pspTransactionId
required
string <= 50

Transaction id by customer from the Sender's system

receiptId
required
string <= 20

Sender's receipt number

amount
required
integer <= 13

Payment amount (in tyiyns), could be from QR or from Payment App/ Sender Bank

qrLinkHash
required
string <= 4

Last 4 symbols of payment link hash string, Field ID=63 from QR

transactionType
required
string
Enum: 10 20 30 40 50 60 70

Transaction type (specified in the table), Sender will get it from the IO when check requisites

Array of objects

Additional fields for the sender, a maximum of 3 additional keys and values can be stored

Responses

Request samples

Content type
application/json
{
  • "qrType": "staticQr",
  • "merchantProvider": "qr.demirbank.kg",
  • "merchantId": "DKIB",
  • "serviceId": "7001",
  • "serviceName": "transfer",
  • "beneficiaryAccountNumber": "11800000971044802",
  • "merchantCode": 4829,
  • "currencyCode": "417",
  • "qrTransactionId": "1732832",
  • "qrComment": "comment",
  • "amount": 40000,
  • "qrLinkHash": "67D9",
  • "customerType": "1",
  • "pspTransactionId": "12512512341",
  • "receiptId": "0924011",
  • "transactionType": "10",
  • "extra": [
    ]
}

Response samples

Content type
application/json
{
  • "transactionId": "fbded76a-9fc6-42d8-b0a0-e7e7110e0cc7",
  • "status": 20,
  • "transactionType": "10",
  • "amount": 40000,
  • "commission": 0,
  • "senderTransactionId": "12512512341",
  • "senderReceiptId": "0924011",
  • "senderBic": "11800100",
  • "beneficiaryBic": "11100100",
  • "createdDate": "2022-11-01T12:00:00Z",
  • "executedDate": "",
  • "extra": [
    ]
}

Execute transaction

path Parameters
transactionId
required
string

Transaction ID from the Operator's system

header Parameters
H-PSP-TOKEN
required
string

Token for Payment system/ Sender Bank

H-PSP-ID
required
string

Payment system/ Sender bank indentificator

H-HASH
required
string

Signature of request

Responses

Response samples

Content type
application/json
{
  • "transactionId": "fbded76a-9fc6-42d8-b0a0-e7e7110e0cc7",
  • "status": 20,
  • "transactionType": "10",
  • "amount": 40000,
  • "commission": 0,
  • "senderTransactionId": "12512512341",
  • "senderReceiptId": "0924011",
  • "createdDate": "2022-11-01T12:00:00Z",
  • "executedDate": "2022-11-01T12:01:00Z"
}

Check status

The sender can send a status check request to the Interaction Operator. This request is for cases where, for whatever reason, the sender has not received the final status of the transaction (success/cancel).

path Parameters
transactionId
required
string

Transaction ID from the Operator's system

header Parameters
H-PSP-TOKEN
required
string

Token for Payment system/ Sender Bank

H-PSP-ID
required
string

Payment system/ Sender bank indentificator

Responses

Response samples

Content type
application/json
{
  • "transactionId": "fbded76a-9fc6-42d8-b0a0-e7e7110e0cc7",
  • "status": 50,
  • "transactionType": "10",
  • "amount": 40000,
  • "commission": 0,
  • "senderTransactionId": "12512512341",
  • "senderReceiptId": "0924011",
  • "createdDate": "2022-11-01T12:00:00Z",
  • "executedDate": "2022-11-01T12:01:00Z"
}

Beneficiary part API's

Beneficiary Bank/PSP gets request from the Interaction Operator and responses with the related response API's.

Check requisites

path Parameters
qrVersion
required
string

Version of QR, by default "1", Field ID=00 from QR

header Parameters
H-HASH
required
string

Signature of request

Request Body schema: application/json
Array
qrType
required
string
Enum: "staticQr" "dynamicQr"

Payment link type, Field ID=01 from QR

merchantProvider
required
string <= 32

Unique identificator of merchant provider (QR Acquirer), Field ID=32, SubID=00 from QR

merchantId
string <= 32

Service provider name, Field ID=59 from QR

serviceId
string <= 32

Service code in the Payment system of QR Acquirer, Field ID=32, SubID=01 from QR

serviceName
string <= 32

Service name in the Payment system, Field ID=33 SubID=01 from QR

beneficiaryAccountNumber
string <= 32

Unique identifier of the payer within the service (лицевой счет), Field ID=32, SubID=10 from QR

merchantCode
required
integer <= 4

Service provider code (MCC), Field ID=52 from QR

currencyCode
required
string <= 3

Currency, by default always "417", Field ID=53 from QR

qrTransactionId
string <= 32

Transaction ID in the QR Acquirer system, Field ID=32, SubID=11 from QR

qrComment
string <= 32

Comment for payment, Field ID=34

amount
required
integer <= 13

Payment amount (in tyiyns), could be from QR or from Payment App/ Sender Bank

qrLinkHash
required
string <= 4

Last 4 symbols of payment link hash string, Field ID=63 from QR

Responses

Request samples

Content type
application/json
{
  • "qrType": "staticQr",
  • "merchantProvider": "qr.demirbank.kg",
  • "merchantId": "DKIB",
  • "serviceId": "7001",
  • "serviceName": "transfer",
  • "beneficiaryAccountNumber": "11800000971044802",
  • "merchantCode": 4829,
  • "currencyCode": "417",
  • "qrTransactionId": "1732832",
  • "qrComment": "comment",
  • "amount": 40000,
  • "qrLinkHash": "67D9"
}

Response samples

Content type
application/json
{
  • "beneficiaryName": "c***e A***o",
  • "customerType": "1"
}

Create transaction

path Parameters
qrVersion
required
string

Version of QR, by default "1", Field ID=00 from QR

header Parameters
H-HASH
required
string

Signature of request

Request Body schema: application/json
Array
transactionId
required
string <uuid>

Transaction ID from the Operator's system

amount
required
integer <= 13

Payment amount (in tyiyns)

qrType
required
string
Enum: "staticQr" "dynamicQr"

Payment link type, Field ID=01 from QR

merchantProvider
required
string <= 32

Unique identificator of merchant provider, Field ID=32, SubID=00 from QR

merchantId
string <= 32

Service provider name, Field ID=59 from QR

serviceId
string <= 32

Service code in the Payment system, Field ID=32, SubID=01 from QR

serviceName
string <= 32

Service name in the Payment system, Field ID=33 SubID=01 from QR

beneficiaryAccountNumber
string <= 32

Unique identifier of the payer within the service (лицевой счет), Field ID=32, SubID=10 from QR

merchantCode
required
integer <= 4

Service provider code (MCC), Field ID=52 from QR

currencyCode
required
string <= 3

Currency, by default always "417", Field ID=53 from QR

qrTransactionId
string <= 32

Transaction ID from QR, Field ID=32, SubID=11 from QR

qrComment
string <= 32

Comment for payment, Field ID=34

qrLinkHash
required
string <= 4

Last 4 symbols of payment link hash string, Field ID=63 from QR

transactionType
required
string
Enum: 10 20 30 40 50 60 70

Transaction type (specified in the table)

senderTransactionId
required
string <= 50

Transaction id from the Sender's system

senderReceiptId
required
string <= 20

Sender's receipt number

Responses

Request samples

Content type
application/json
{
  • "transactionId": "fbded76a-9fc6-42d8-b0a0-e7e7110e0cc7",
  • "amount": 40000,
  • "qrType": "staticQr",
  • "merchantProvider": "qr.demirbank.kg",
  • "merchantId": "DKIB",
  • "serviceId": "7001",
  • "serviceName": "transfer",
  • "beneficiaryAccountNumber": "11800000971044802",
  • "merchantCode": 4829,
  • "currencyCode": "417",
  • "qrTransactionId": "1732832",
  • "qrComment": "comment",
  • "qrLinkHash": "67D9",
  • "transactionType": "10",
  • "senderTransactionId": "12512512341",
  • "senderReceiptId": "0924011"
}

Response samples

Content type
application/json
{
  • "transactionId": "fbded76a-9fc6-42d8-b0a0-e7e7110e0cc7",
  • "status": 20,
  • "transactionType": "10",
  • "amount": 40000,
  • "beneficiaryName": "c***e A***o",
  • "customerType": "1",
  • "receiptId": "7218199",
  • "createdDate": "2022-11-01T12:00:00Z",
  • "executedDate": ""
}

Execute transaction

path Parameters
transactionId
required
string

Transaction ID from the Operator's system

header Parameters
H-HASH
required
string

Signature of request

Responses

Response samples

Content type
application/json
{
  • "transactionId": "fbded76a-9fc6-42d8-b0a0-e7e7110e0cc7",
  • "status": 20,
  • "transactionType": "10",
  • "amount": 40000,
  • "beneficiaryName": "c***e A***o",
  • "customerType": "1",
  • "receiptId": "7218199",
  • "createdDate": "2022-11-01T12:00:00Z",
  • "executedDate": "2022-11-01T12:02:00Z"
}

Check status

The Interaction Operator can send a status check request to the Beneficiary Bank/PSP. This request is for cases where, for whatever reason, the final status of the transaction has not been received (success/cancel/error).

path Parameters
transactionId
required
string

Transaction ID from the Operator's system

header Parameters
H-HASH
required
string

Signature of request

Responses

Response samples

Content type
application/json
{
  • "transactionId": "fbded76a-9fc6-42d8-b0a0-e7e7110e0cc7",
  • "status": 50,
  • "transactionType": "10",
  • "amount": 40000,
  • "beneficiaryName": "c***e A***o",
  • "customerType": "1",
  • "receiptId": "7218199",
  • "createdDate": "2022-11-01T12:00:00Z",
  • "executedDate": "2022-11-01T12:02:00Z"
}

Update status API's

It will be implemented on both sides: Operator, Merchant.

Update status

During the 'Execute transaction' phase, if the Beneficiary does not return the final status, after the completion of the transaction, the Beneficiary will send an 'Update status' request to the 'Interaction Operator.' The received response will be forwarded to the 'Sender' by the 'Interaction Operator.' In addition, the 'Interaction Operator' may send an 'Update status' request to the Beneficiary or the Sender in case of a timeout. The method must be implemented on both the Operator's side and the Merchant's side.

  • Operator's URL: /operator-api/api/v1/payment/qr/{version}/tx/update/{transactionId}
  • Merchant's URL: /qr/{version}/tx/update/{transactionId}
path Parameters
transactionId
required
string

Transaction ID from the Operator's system

header Parameters
H-PSP-TOKEN
required
string

Token for Payment system/ Sender Bank (for calling Operator API's)

H-PSP-ID
required
string

Payment system/ Sender bank indentificator (for calling Operator API's)

H-HASH
required
string

Signature of request

Request Body schema: application/json
Array
status
required
integer
Enum: 30 40 50

Transaction status (specified in the table), in this API only final status should be send

updateDate
required
date-time

Transaction status update date-time

Responses

Request samples

Content type
application/json
{
  • "status": 50,
  • "updateDate": "2022-11-01T12:02:00Z"
}